Macworld Expo - Develope…Central & Net Innovations/Developer Central and Net Innovators (MacWorld Expo) (January 1999).iso/Developer Central/Metrowerks CodeWarrior/CodeWarrior Pro 4 Release Notes/Java Notes/Class Wrangler ReadMe

Text File | 1998-08-25 | 18.3 KB | 423 lines | [TEXT/CWIE]

========================================================================
Metrowerks Class Wrangler Read Me
========================================================================

Version: 1.4
Date:    8-25-98
by Greg Bolsinga, Peter Lewis, Tim Freehill

========================================================================
About Class Wrangler
========================================================================

Class Wrangler is a utility that allows you to view and alter the
contents of an uncompressed .zip file or a .zip file compressed with
the deflate algorithm. This algorithm is used by the zlib library and
JAR files in JDK 1.1. It is not intended to be used as a general
purpose .zip tool because it only handles .zip files in a specific
format. This format is widely used, however.


========================================================================
Drag and Drop
========================================================================

Dropping a folder onto the Class Wrangler application icon will have
two possible effects:

1) If a file is already open in Class Wrangler, the files within the
folder hierarchy can optionally be added to the frontmost document,

or

2) a new archive will be created containing all the files in the
hierarchy.

Dropping a single file on Class Wrangler will have a similar effect. If
there are duplicate files already in the open archive location, Class
Wrangler will prompt you to overwrite the existing files.

Of course, dropping a file of type 'ZIP ' or 'ZIPf' on the application
will open it.


========================================================================
Archive Table
========================================================================

When a archive is opened using Class Wrangler, the contents thereof
will be displayed in the table on the lower portion of the document's
window. This table will list all the items in the archive, keeping the
archive hierarchy intact. Showing the full path or only the item name
can be set in the preferences. These paths are used when extracting the
files, and are used by Java Virtual Machines that can read items
directly from an archive.

When files are added to the archive, they are placed where they are
dropped. This works similarly to dragging items the Finder's List view.
However, .class and .java files are parsed to the the 'real' name. This
will be placed into the correct hierarchy based upon their fully
qualified name. This will also 'fix' files which had to have their
names shortened for one reason or another.

The position of classes in the table reflects the namespace hierarchy of
the classes in the zip file. This means that inner classes will be
displayed as children of their outer class. These inner and outer
classes are the same as 'regular' classes in all other respects.

The Manifest file, if present, isn't displayed in the table. The
manifest information is available in the archive window and the
manifest window.

The user can set the bean state for a class item in the archive window.
The column with the Java Bean at the top indicates if the item is a
bean. A dot means that the item is a bean, otherwise it isn't. Click in
the cell to toggle the bean state of the item.

The user can edit the manifest information for an item by selecting it
in the archive window and choosing the Edit Manifest command in the
Package window. A new window will come up that will allow the user to
change the editable manifest tags for the item. Any manifest tags that
aren't recognized by Class Wrangler will be in the 'Other' pane. It
is a plain editable text pane. You can edit the manifest tags here. By
Sun's definition, manifest files are simply text files in the JAR file.
As new tags are know, a UI should be added for them by the next release
of Class Wrangler. The user can drag text to both of these panes.

You can type the name of an item to select it automatically. Typing
tab will select the next visible item alphabetically, and shift-tab will
select the previous visible item alphabetically. What you type ahead
will be displayed at the top of the archive window.

Items that haven't yet been saved in the archive are drawn in italics.
Items which didn't pass verification of the manifest file are drawn in
the user preference color for Invalid Items.

Class Wrangler will always save archive files with a ".zip" or ".jar"
extension.


========================================================================
Save Manifest File
========================================================================

In the JAR specificaton, the manifest file is simply a text file. By
choosing this command in the File menu, the user can output the manifest
file. It can be added to a java project that is building an archive
file. The Java Linker will add the appropriate manifest data for the
named items in the output. The manifest file can only be saved from an
archive that is saved itself.


========================================================================
Import Manifest File
========================================================================

The user can import a manifest file into the active archive. This
command is in the Package menu. Any items in the archive that match a
name in the imported manifest file will have it's manifest data changed
to the imported data.


========================================================================
Compressed State
========================================================================

After opening a document, the compressed icon is file in a compressed
state if the file is compressed, or a plain file if it is not
compressed. A Compressed menu item in the Package menu also indicates
the compressed state of the archive. Clicking on the icon or selecting
the menu item toggles this state.


========================================================================
Manifest State
========================================================================

After opening a document, the jar icon appears full if the file has
manifest information, or appears empty if it has no manifest
information. A Manifest menu item in the Package menu also indicates
the manifest state of the archive. Clicking on the icon or selecting
the menu item toggles this state.


========================================================================
Add Files Button/Menu Item
========================================================================

Selecting this function allows you to add files to the frontmost open
archive. When Add Files is chosen, you will be presented with the same
style Add Files dialog the IDE uses. You can then select files to add.

When Done is clicked on this dialog, these files will be added to the
list of files already displayed in the archive.  If there are any
duplicate files being added, you will be prompted before they are
overwritten. Added files will be drawn in italics, denoting that they
have not yet been saved to the disk. You MUST save the document before
they are actually added to the file.

These files are added to the root of the archive, unless they are files
which define their own hierarchy (such as .class or .java files).


========================================================================
Extract Files Button/Menu Item
========================================================================

Selecting this function allows you to extract the selected file(s) from
the frontmost open archive.

The extracted files will be put into a folder of the same name as the
project at the selected destination position. A folder hierarchy
reflected that shown in the archive will also be created. For example,
if you extract java/awt/Graphics.class from classes.zip, it will be put
in the folder :java:awt: at the location you've chose. If the folder
hierarchy already exists at that location, you will be prompted to
overwrite the existing files.

Files are extracted using the file mappings set by Internet Config.


========================================================================
Delete Files Button/Menu Item
========================================================================

Selecting this function allows you to delete the selected file(s) from
the frontmost open archive.

When this function is selected, the highlighted items will be removed
from the window's list. When the resulting archive is saved, only those
items shown in the list will be saved in the resulting archive. Note
that the deleted files are not actually removed from the archive on
disk until the archive is saved.


========================================================================
Add Directory Menu Item
========================================================================

The user can add a directory to the active archive by selecting the Add
Directory command from the Package menu. In the resulting dialog box,
enter the full pathname of the directory to be added. If an item is
selected in the archive window, it's full pathname will already be in
the window, to allow the user to easily edit it. Please note that
directories must be separated by '/'.


========================================================================
Information Button/Get Info Menu Item
========================================================================

Selecting this function allows you to see pertinent information about
the selected .class file(s) from the frontmost open archive.

When this function is selected, the highlighted .class file will be
disassembled. A new window will be opened which gives the class's full
package name, its size, its super class name, its source file name, the
interfaces it implements, the fields in the class (both type and name),
and the methods in the class (including access information, return type,
its name, and parameter types).

The information windows are associated with the archive where the
information was gathered from. If the associated archive is closed, all
of its information windows will also be closed.

You can copy the signature used by java for a selected method by holding
down the option key while copying. The java signature is very useful
when writing java native methods.


========================================================================
Edit Manifest Menu Item
========================================================================

Selecting this command allows the user to edit the manifest data for the
currently selected item in the active archive.

The manifest data is displayed for the user to verify and modify.
Certain items, like the name and MD5 & SHA hash codes, cannot be
modified. The java bean state and the design time only state have
checkboxes to indicate whether or not they are on. The depends list is a
list of items. Any text can be dragged to this pane in order to add it
to the list. The other edit field holds all manifest tags that are not
yet specifically parsed by Class Wrangler. These could include new tags
from Sun or special user-defined tags. Since Manifest files are only
text files, this provides a rough, but completely extensionable way to
edit manifest tags.

Please see Sun's docs for the complete explanation of manfiest tag and
manifest file format. In a nutshell, there is a specific format for the
tags: <name>: <value>. Tags must be delimited with "\r\n" line breaks.
Class Wrangler assures that this is the case in the 'other' pane.


========================================================================
Find Main Classes Menu Item
========================================================================

Selecting this menu item in the Package Menu will draw all java classes
that contain methods in the user preferred color. This will be useful
in JDK 1.2, which has .jax files.


========================================================================
Disassemble Class Menu Item
========================================================================

Selecting this menu item in the Package Menu will display the
disassembly for the selected java class files. The disassembly is
savable, but not editable. It's the same disassembly code as used in the
IDE.


========================================================================
View Menu Item
========================================================================

Selecting this menu itme in the Package Menu will display the currently
selected text files in separate text windows. The text is savable, but
not editable. Class Wrangler determines if a selected item in the
archive is a text file by using Internet Config to map the item's
extension to a MacOS file type.


========================================================================
Using the Clipboard
========================================================================

Items can be manipulated in Class Wrangler with the clipboard. The text
of the selected items is also copied to the clipboard.


========================================================================
Using Drag and Drop
========================================================================

Items can be dragged between Class Wrangler windows. These behave as if
items had be extracted from one archive and added to the new one. The
items are added to the location highlighted in the hierarchy. The text
of the selected items is also dragged about.

Items can also be dragged to a Class Wrangler window from the Finder
and to the Finder. When dragging to a window, Class Wrangler will add
the files to the location highlighted in the hierarchy. When dragging to
the Finder from a Class Wrangler window, Class Wrangler behaves as if
the files were extracted to the destination folder. Class Wrangler
accepts any type of file or folder dragged to the document window.
Class Wrangler will iterate through all files and into all folders
in a dragged folder. If you don't want to create the folder hierarchy
for the dragged out items in the Finder, option drag the item. It will
place it exactly where you drop it.

However, when dragging .java or .class files to an archive window, they
will ignore the drop location, and be placed at their correct fully
qualified name position. This is obtained by parsing the file for
this information.

Note: You can affect the text copied or dragged in Class Wrangler with
the option key. When it is pressed while copying or dragging, it
imports the text as a valid Java import statement which can then be
placed directly into Java source files. If not, it simply copies the
full path name of the selected files.

The user can drag text to the Manifest Editing Window's 'Depends' and
'Other' panes. A useful operation is to drag items from the archive
window to the 'Depends' pane. Now the item referenced from the
Manifest Editing window depends on that item in the archive.


========================================================================
Comparing Archives
========================================================================

Class Wrangler can compare archive files. This way the user can
determine what has changed from one archive file to another. To Compare
archive files, select the "Compare Archive Files..." item from the File
menu.

A dialog box similar to the IDE's Compare Files dialog box comes up.
Click on the choose button to select archive files to compare. Files can
also be dragged and dropped to the area where the file's path name is
displayed.

There's a checkbox which selects whether the compare should be on item's
contents or not. If it isn't checked, only the item names are compared,
and the results will indicate which items are unique in each archive. If
the checkbox is checked, the item names and the contents of items with
the same name are compared. The results will indicates which items are
unique and which items are different.

The compared archives are displayed in regular Class Wrangler archive
documents. However, unique items are drawn in the user preference Unique
Items color, and different items are drawn in the user preference
Different Items color.


========================================================================
Preferences
========================================================================

There is a preference setting to turn off the default of asking for a
file to open when Class Wrangler is started without opening a document.

There is a setting to toggle whether the full path name of the .class
should be displayed. If not, only the directory names and .class names
are displayed. For example, java/awt/Graphics.class with full path
names would be displayed:

    java/
        java/awt/
            java/awt/Graphics.class

With full path names off:

    java
        awt
            Graphics.class

There is a setting to toggle whether packages should be open in
collapsed mode or not. When opening in collapsed mode, only the top
level packages/classes will be seen. They can be opened in the regular
fashion. When not opening in collapsed mode, every package will be
completely shown.

The user can set whether the manifest file (if present) is verified
when opening an archive. Invalid items in the archive are drawn in
the user preference color for Invalid Items.

There is a preference to choose how a filename should be truncated on
the Macintosh if the filename is too long. You can select the start,
middle or the end. The file's extension is preserved in the truncation
as well. Also, if an item's filename is shortened, the full java name
for the item will be entered into the item's Finder Info comments.

There is a preference to choose the delay for the type ahead feature.
One second (60 ticks) is the default value. There is also a preference
to use the full package name for the type ahead. For example, if you'd
like to select "java.util", this preference on would require you to
type "java/util" instead of simply "util". Please note the "/" instead
of the ".".

The user can set the color for special display items in the archive
table. The color can be selected for Invalid Items, Unique Items,
Different Items, and the Main Classes. The respective defaults are red,
green, blue, & purple.


========================================================================
Contacting Metrowerks
========================================================================

For bug reports, technical questions, and suggestions, please use the
forms in the Release Notes folder on the CD, and send them to

[e-mail]

See the CodeWarrior on the Nets document in the Release Notes folder for
more contact information, including a list of Internet newsgroups,
online services, and patch and update sites.

========================================================================
Greg Bolsinga
Metrowerks Corporation